Add a new tenant

The first step to creating a new tenant is to create a database in SQL Server, and then prepare it for use by applying the 'DB UPGRADE' program. Once that is complete, use the Tenants screen in IPS Manager to add a new tenant to your IPS Server deployment.

Tenant database creation and DBUPGRADE

In an SQL Server management tool, create a new database.

As an alternative, you may have been provided a starter database (as a BAK file) by Quorum Software Support. In this case, use the 'Restore Database' option in SQL Server.

The database name is at your choice; you will need to enter the name into the tenant configuration in IPS Manager.

The two essential settings for the new database are:

• Collation: Latin1_General_100_CI_AS_WS
• Compatibility level: SQL Server 2016 (130)

Next, run DBUPGRADE. This requires Microsoft Office (version 2010 or later) to be installed in the machine where the upgrade program is running (this can be any machine with network access to the SQL Server machine).

If you have used a starter database provided by Quorum Support, please check if this upgrade step is required. The upgrade program will temporarily grow the SQL Server logs due to creation of recovery log data; if the operational database Recovery Model setting is not 'Simple' then it is recommended to temporarily switch it to 'Simple' during the upgrade, in order to avoid the possibility of disk space overflow.

Use the 'DBUpgrade' program, downloadable from https://clients.aucerna.com/products/downloads. Use the file 'dbupgrade_204XYYYY.zip', where 'X' is the update number and 'YYYY' is the build number.

Note that the DBUPGRADE version number must be the same as the version of IPS Server/Planning Space that you are installing. If you are not installing the current latest version, check with Quorum Support for what is needed.

Note: It is recommended to disable realtime antivirus software if you experience slow performance of the DBUPGRADE programs.

Run the executable file 'Palantir.DBUpgrade.exe'.

The SQL Server account that you use here needs to have the permission role 'db_owner' for the tenant database. If the SQL Server account is linked to your current Windows login, click the box Use Trusted Connection. Otherwise, type in the User name and Password of a SQL Server-authenticated account.

In the Server field, click the down arrow to show a list of the SQL Server instances detected in the current Windows domain, and select the name of the SQL Server instance that you are using. You can also type the instance name into the input box.

In the Database field, you can type in the name of the tenant database, or click the down arrow to show the list of databases found in the SQL Server instance (note that you may not see any list, depending on the VIEW permissions of the SQL Server account that is being used).

If the SQL Server is configured with a self-signed or trusted certificate, you should enable SSL-based encryption by ticking the box Use transport encryption. If you tick Trust server certificate then the DBUPGRADE program will trust any certificate that is offered by the SQL Server machine; otherwise the Windows certification validation must be satisfied.

The check box Check Excel dependencies should keep the default setting (checked).

Click the Connect button, and the program will check that the database is ready to be upgraded, then click the Next button to start the upgrade process.

A log file will be created at: 'C:\Users\{Username}\AppData\Local\Palantir\{DatabaseName}.txt'.

Set the database permissions for the SQL Server account

The SQL Server account used by IPS Server must have permissions on the new database as follows: 'db_datareader', 'db_datawriter', and 'pes_datawriter' (the last permission type is added by the DBUPGRADE program).

Create a new tenant in IPS Manager

Open IPS Manager, click Tenants in the left-hand menu, and click the New button to open a dialog:

Type in a name for the new tenant. The name is at your choice; this name will appear in the URL for running Planning Space, so the name should be appropriate, not too long, and easy to type. Click the Create button.

Important: Rules for tenant naming
- A tenant name can have a maximum of 50 characters, it must start with a letter, and it can only contain letters, numbers, dashes, and underscores.
- The tenant name cannot clash with any resource path that is used by IPS Server. These are: 'admin', 'license', 'licenseserver', and 'monitor'.
- Tenant names are not case-sensitive, hence a tenant named 'europe' could also be referred to by 'Europe' or 'EUROPE', etc. These are all the same tenant name.

This creates a new tab ('UAT-1' in the example screenshot) for the tenant configuration:

Note: You can also use the Copy function to make a copy of an existing tenant configuration, under a new tenant name. Then you can edit the configuration as required for the new tenant.

The new tenant's Data source (i.e., database), Cluster shared temp folder and Identity Provider (if ADFS-based authentication is used) need to be configured now.

The 'Cloud Storage' setting is only required if Azure SQL is used to run the tenant database. (See Databases using Azure SQL.)

Assign the tenant database

Important: Authentication of the connection to the tenant data source can use the IPS Service Account (with Windows authentication) or an SQL Server-authenticated account. SQL authentication is recommended, because it allows the cluster shared Temp folder to be located anywhere on the network. However, if the IPS Service Account is used then the Temp folder must be located on the same machine as the SQL Server; this is a security restriction imposed by SQL Server to restrict bulk insert operations. This security restriction can be avoided, and the shared Temp folder placed anywhere on the network, by means of more complex system configuration: Kerberos delegation must be configured, and required SETSPN commands must be performed by a Domain Administrator. Please contact Quorum Support for instructions for running IPS Server and SQL Server in this configuration.

Click the Assign button to open the Assign data source dialog:

Server Name: Type the name of the SQL Server instance where the tenant database is stored.

Select IPS Service account if you have created a SQL Server account that is linked to the IPS Service Account in Windows; otherwise select Use SQL user name and password and type in the User name and Password of a SQL Server-authenticated account.

If the SQL Server is configured with a self-signed or trusted certificate then tick Use transport encryption to enable SSL-based encryption of traffic between the IPS Server machine(s) and the SQL Server machine. If you tick Trust server certificate then the IPS Server machines will automatically trust any certificate that is offered by the SQL Server machine; otherwise the Windows certification validation must be satisfied.

Database name: Type in the database name. Click the Test button to verify the database can be accessed and is ready to be used.

Click the Ok button to save the information, and close the dialog.

Set the Cluster shared temp folder

Enter the path for the Cluster shared temp folder in the input box.

(See Cluster shared Temp folder.)

Set the Identity Provider and Token Lifetime

These settings are required when an Identity Provider server or service is used to authenticate SAML2 user accounts.

Token lifetime has a default value of 15 minutes. See Bearer Token lifetime.

For Identity Provider, click the Edit button and follow the instructions at Identity Provider (IdP) setup.

Authentication methods

The allowed authentication methods (Local, SAML2, Windows Active Directory) can be enabled or disabled for each tenant in IPS Manager.

See Tenant authentication methods.

Save the settings for the new tenant

Click the Save all changes button to save the settings for the new tenant.

Important: An initial administrator user is created for the tenant, with username 'Administrator' and password 'Administrator'.